home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 029a / asort11.zip / ASORT.TXT < prev   
Text File  |  1991-12-09  |  12KB  |  265 lines
  1.            ASORT Version 1.1 - Copyright 1989 Roger E. Donais
  2.  
  3.  
  4. GENERAL:
  5.  
  6. ASORT is a generic extract and sort utility.  The input file is expected
  7. to be a carriage return - line feed delimited ascii text file.  Source
  8. lines may be random length, but cannot exceed 4096 characters.
  9.  
  10. Type ASORT with no parameters to obtain an on-screen command/option
  11. summary.
  12.  
  13. The sort will *NOT* be attempted if there is than 48k of memory, and
  14. will abort at the end of the first pass if there is insufficient memory
  15. for the merge buffers. The elapsed time to reach this point will depend
  16. on your disk through-put, which is typically 3% longer than the time it
  17. takes to read and write the file in question using a 25 mHz 486 with a
  18. 680 Meg ESDI Drive reporting a 16ms access and 1012 Meg transfer rate.
  19.  
  20.  
  21. OUTPUT FILE:
  22.  
  23. The output file is defined as one or more segments that are to be
  24. extracted from each source line.  Each extract segment is defined as a
  25. starting column and ending column separated by a colon, or as a starting
  26. column and segment length separated by the letter "x".  Any extract
  27. segment that is beyond the end of a short source line will be space
  28. filled. Portions of the source line that are not described in the
  29. extract definition are discarded.  Each line of the completed extract
  30. file will be the combined length of the concatenated extract segments
  31. followed by an ASCII carriage-return and line-feed character sequence.
  32. Multiple segment descriptions are comma separated with no intervening
  33. spaces.  The resulting output file is a series of fixed length
  34. carriage-return/line-feed delimented records.
  35.  
  36.         Don't forget to add 2 additional characters for the
  37.         CR/LF to the declared record length when using random
  38.         access tecniques to access the resulting output file.
  39.  
  40.  
  41. SORT KEY:
  42.  
  43. The sort key is defined as one or more key segments that are to be
  44. constructed from each source line.  Each key segment is defined as a
  45. starting column and ending column separated by a colon, or as a starting
  46. column and field length separated by the letter "x".  Multiple sort key
  47. segment descriptions are comma separated with no intervening spaces.
  48.  
  49. The key description list is read from left to right.  The left most
  50. segment definition representing the major sort key and the right most
  51. segment definition representing the minor, or least significant key.
  52.  
  53. Any key segment that is beyond the end of a short source line will be
  54. padded with spaces.  This means that non-existent key segments will
  55. have the same collating sequence as an existing space filled key
  56. segment.
  57.  
  58. An optional letter suffix may be applied to each sort key segment to
  59. control case sensitivity and specify the ascending or descending order
  60. to be applied to that key segment.  The letter "A" or "a" specifies an
  61. ascending sort sequence, and the letter "D" or "d" specifies a
  62. descending sequence.  Use an uppercase "A" or "D" to force conversion to
  63. upper case, thereby removing case sensitivity; and use a lowercase "a"
  64. or "d" to retain case sensitivity.
  65.  
  66. A pseudo numeric key segment may be declared by appending a minus sign
  67. "-", to any of the lettered options, or may be appended directly to the
  68. physical description.  If used, this option must be the last character
  69. of a segment description.
  70.  
  71. Each segment of the sort key retains its ASCII characteristics,
  72. therefore non-numeric characters may be contained in a right justified
  73. numeric field.  Entries are determined to be negative when the first
  74. non-space character is a minus sign, "-"; the last non-space character
  75. is a minus sign, "-"; or when the first non-space character is a left
  76. parenthesis, "(", and the last non-space character is a right
  77. parenthesis, ")".  The minus sign, or parenthesis defining a negative
  78. value are discared, leading and trailing spaces are removed from the
  79. remaining portion, and the result is then right justified in a space
  80. filled field.
  81.  
  82. Justification and case conversion are applied only to the sort key. Each
  83. section of the data extract is faithfully copied from the source file
  84. retaining the same character case, justification, and/or centering that
  85. occurred in the original file.
  86.  
  87. If the completed sort records are larger than the available memory,
  88. ASORT will create an intermediate work file. Sufficient free disk space
  89. must be available on the scratch drive to contain the work files, and
  90. sufficient memory must exist to provide a minimal buffer for each
  91. intermediate block flushed to disk.
  92.  
  93.  
  94. USAGE:
  95.  
  96. ASORT is invoked using the following syntax -
  97.  
  98.   asort <infile >outfile {extract} {sort key} [temp path]
  99.  
  100.   where   <infile                  is a standard DOS redirected
  101.                                    input specification.
  102.  
  103.           >outfile                 is a standard DOS redirected output
  104.                                    specification.
  105.  
  106.           {extract}                is a comma separated field
  107.                                    description list.
  108.  
  109.           {sort key}               is a comma separated field
  110.                                    description list.
  111.  
  112.           [temp path]              is an optional DOS drive/path
  113.                                    specification for the
  114.                                    intermediate work file.
  115.  
  116.   and each extract and sort key field entry is specified as -
  117.  
  118.       {start column}:{end column} OR {start column}X{field width}
  119.  
  120.   and each sort key field may have one lettered and/or a justification suffix
  121.  
  122.           a        case sensitive ascending sequence (default option)
  123.           d        case sensitive descending sequence
  124.           A        case insensitive ascending sequence
  125.           D        case insensitive descending sequence
  126.           -        right justified / pseudo numeric
  127.  
  128.  
  129. EXAMPLE:    { Single line command, multiple lines for display only }
  130.  
  131. asort  <e:\test1.def  >tempdata.$$$
  132.             1:1,6:13,53x2,65:68,55x2,92:98
  133.                   1:1D,6:13A,92:98-,53x2A,65:68A,55x2-  D:\
  134.  
  135. Will extract data from TEST1.DEF located in the root directory of drive
  136. E: and write the sorted result to TEMPDATA.$$$ located in the current
  137. directory of the default drive. The root directory of drive D: will be
  138. used to contain the intermediate work file.
  139.  
  140. The extract will consist of the concatenation of
  141.  
  142.                  column 1 through column 1
  143.          and     column 6 through column 13
  144.          and     two characters starting at column 53
  145.          and     column 65 through column 68
  146.          and     two characters starting at column 55
  147.          and     column 92 through column 98
  148.  
  149. Records (carriage return - line feed delimited lines) will be sorted
  150. from major to minor keys as -
  151.  
  152.          column 1 through column 1              upper case descending
  153.          column 6 through column 13             upper case ascending
  154.          column 92 through column 98            ascending numeric
  155.          two characters starting at column 53   upper case ascending
  156.          column 65 through column 68            upper case ascending
  157.          two characters starting at column 55   ascending numeric
  158.  
  159. MESSAGES:
  160.  
  161. All runtime messages are written to the stderr device, and will, by
  162. default, be directed to the crt display.  When invoked with no
  163. parameters, ASORT displays a full screen help message.  Additional
  164. messages that may be displayed are -
  165.  
  166.          ASORT COMMAND ERROR:
  167.                  indicates an error was detected in the command line.
  168.                  The command line will be displayed with a carat (^)
  169.                  marking the position where the error was detected.
  170.  
  171.          ** insufficient memory **
  172.                  indicates that there is not enough memory available to
  173.                  provide the necessary merge buffers.
  174.  
  175.          ** unable to create intermediate file **
  176.                  indicates an error occurred when ASORT attempted to
  177.                  create the intermediate work file (ASORT000.$$$).
  178.  
  179.          ** intermediate file write error **
  180.                  indicates an error occurred when writing to the
  181.                  intermediate work file.
  182.  
  183.          ** output file write error **
  184.                  indicates an error occurred when writing to the
  185.                  redirected stdout file handle.
  186.  
  187. SYSTEM REQUIREMENTS:
  188.  
  189. This release of ASORT was tested using a 9-Meg file consisting of
  190. 128,000 seventy (70) character carriage-return line-feed delimited
  191. records.  The record extract was defined as the original seventy (70)
  192. characters, and the sort key was defined as the first ten (10)
  193. characters.  A TSR was used to consume all but 64k of available memory.
  194. The sort was satisfactorily completed in less than forty-nine minutes
  195. using a 16 mHz 386 equipped with a 16ms MiniScribe 9380E.  The same test
  196. completed in less than five minutes when 490,000 bytes of memory was
  197. reported available by Turbo Power's MAPMEM utility.
  198.  
  199. The largest known task to which ASORT has been applied, was a 219 meg
  200. file consisting of 153 byte records, sorted on a five part key totalling
  201. 96 bytes.  The result of this task was an appalling 7 hours on a 25 mHz
  202. 486 equipped with a 16ms MiniScribe.  (I'll do better next time boss...)
  203.  
  204. If you are concerned about really large files, memory per record and/or
  205. minimal buffer requirement can be estimated as -
  206.  
  207.      9 + extract length + key length + number of numeric sort fields
  208.  
  209. Assuming 100k of memory was available for work space, approximately 600
  210. merge buffers would be available to sort a file of 78 character records
  211. using a 78 character key, which would be sufficient to allow sorting a
  212. 28-Meg file.
  213.  
  214. Naturally, the more memory, the faster the sort!
  215.  
  216. The size of the intermediate file can be computed as the number of
  217. records times the sum of:
  218.  
  219.      (extract length + key length + number of numeric sort fields)
  220.  
  221. Thus, the above example will require approximately 56-meg in order to
  222. produce a 28-meg output file.  Athough memory is an important factor of
  223. speed, it will usually not be the limiting factor for the size file that
  224. can be created.
  225.  
  226. You will know if the existing resources are sufficient to complete the
  227. sort by the end of the first pass. The elapsed time to reach this point
  228. will depend of your disk through-put, and will usually be only 3% longer
  229. than the time it takes to read and write the file in question. The 3%
  230. factor is based upon tests performed using a 25 mHz 486 and the 16ms
  231. access and 1012 Meg transfer provided by a 680 Meg ESDI Drive.
  232.  
  233. SUMMARY:
  234.  
  235. The algorithm has migrated in its present form from Turbo-3, Turbo-4,
  236. Turbo-5, Turbo-C, and finally to the assembly language version presented
  237. here.  Of the high level languages, Turbo-3 performed best, sorting a
  238. 10-meg file of 80 character records using a 10-Mhz Wyze in 35 minutes.
  239. Turbo-4 and 5 took one minute longer.  Turbo Pascal 4 & 5 produced
  240. substantially smaller executable files, but lost the race with Turbo-C
  241. when sorting small files, but performed substantially better when
  242. sorting larger files.  This improvment was probably due to my ability to
  243. control the Pascal heap better than the Turbo-C heap.  For all its
  244. inefficiencies, the assembly version is one fourth the size of the
  245. smallest high level implementation, and six times faster the the best
  246. them.
  247.  
  248. -----------------------------------------------------------------------
  249.                         --- The legal Stuff ---
  250.  
  251. ASORT includes trade secrets and confidential information, which is the
  252. copyrighted intellectual property of Roger Donais. 
  253.  
  254. ASORT may be freely copied and distributed on a non-profit basis, but
  255. may not be sold or traded for monetary value, nor used commercially
  256. without the written consent of the author.
  257.  
  258. ASORT is provided without warranty, expressed or implied, including but
  259. not limited to fitfulness for a particular purpose. The author does not
  260. guarantee the accuracy of the program and accepts no responsibility for
  261. its use.
  262.  
  263.                 Roger Donais (Compuserve ID: 70414,525)
  264.  
  265.